| Server IP : 121.121.20.254 / Your IP : 216.73.216.202 Web Server : Microsoft-IIS/10.0 System : Windows NT WEB-SERVER 10.0 build 20348 (Windows Server 2022) AMD64 User : IUSR ( 0) PHP Version : 8.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Program Files/LibreOffice/help/en-US/text/sbasic/shared/ |
Upload File : |
<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<base href="../../../../">
<noscript><meta http-equiv="refresh" content="0; URL=../../../../en-US/noscript.html"></noscript>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>CreateUnoListener Function</title>
<link rel="shortcut icon" href="media/navigation/favicon.ico">
<link type="text/css" href="normalize.css" rel="Stylesheet">
<link type="text/css" href="prism.css" rel="Stylesheet">
<link type="text/css" href="default.css" rel="Stylesheet">
<script type="text/javascript" src="polyfills.js"></script><script type="text/javascript" src="languages.js"></script><script type="text/javascript" src="en-US/langnames.js"></script><script type="text/javascript" src="flexsearch.debug.js"></script><script type="text/javascript" src="prism.js"></script><script type="text/javascript" src="help2.js" defer></script><script type="text/javascript" src="a11y-toggle.js" defer></script><script type="text/javascript" src="paginathing.js" defer></script><script type="text/javascript" src="en-US/bookmarks.js" defer></script><script type="text/javascript" src="en-US/contents.js" defer></script><script type="text/javascript" src="help.js" defer></script><meta name="viewport" content="width=device-width,initial-scale=1">
</head>
<body>
<header id="TopLeftHeader"><a class="symbol" href="en-US/text/shared/05/new_help.html"><div></div></a><a class="logo" href="en-US/text/shared/05/new_help.html"><p dir="auto">LibreOffice 24.2 Help</p></a><div class="dropdowns"><div class="modules">
<button type="button" data-a11y-toggle="modules-nav" id="modules" aria-haspopup="true" aria-expanded="false" aria-controls="modules-nav">Module</button><nav id="modules-nav" hidden=""></nav>
</div></div></header><aside class="leftside"><input id="accordion-1" name="accordion-menu" type="checkbox"><label for="accordion-1" dir="auto">Contents</label><div id="Contents" class="contents-treeview"></div></aside><div id="SearchFrame"><div id="Bookmarks">
<input id="search-bar" type="search" class="search" placeholder="Search in bookmarks for chosen module" dir="auto"><div class="nav-container" tabindex="0"><nav class="index" dir="auto"></nav></div>
</div></div>
<div id="DisplayArea" itemprop="softwareHelp" itemscope="true" itemtype="http://schema.org/SoftwareApplication">
<a name="createunolistener"></a>
<a name="bm_id3155150"></a>
<meta itemprop="keywords" content="CreateUnoListener function">
<h1 id="hd_id3155150" dir="auto">
<a name="CreateUnoListener"></a>CreateUnoListener Function</h1>
<p id="par_id3149346" class="paragraph" dir="auto">Creates a Listener instance.</p>
<p id="par_id3153681" class="paragraph" dir="auto">Many Uno objects let you register listeners with dedicated listener interfaces. This allows to listen for specific events and call up the appropriate listener method. The <span class="literal">CreateUnoListener</span> function sets a listener interface associated to an UNO object. The listener interface is then bound to its associated object.</p>
<div class="embedded">
<a name="functsyntax"></a>
<h3 id="hd_id061420171139089682" dir="auto">Syntax:</h3>
</div>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
CreateUnoListener( Prefix As String, Typename As String) As Object
</code></pre></div>
<div class="embedded">
<a name="functparameters"></a>
<h3 id="hd_id061420171139084157" dir="auto">Parameters:</h3>
</div>
<p id="par_id531666699350617" class="paragraph" dir="auto"><span class="emph">Prefix</span>: A text prefix used in BASIC subroutines that handle events.</p>
<p id="par_id281666699351161" class="paragraph" dir="auto"><span class="emph">Typename</span>: A fully qualified UNO listener interface name.</p>
<div class="embedded">
<a name="functvalue"></a>
<h3 id="hd_id061420171139087480" dir="auto">Return value:</h3>
</div>
<p id="par_id241666699584417" class="paragraph" dir="auto">The UNO service corresponding to the <span class="literal">Typename</span> listener interface name, <span class="literal">Null</span> value otherwise.</p>
<div class="embedded">
<a name="functexample"></a>
<h3 id="hd_id061420171139088233" dir="auto">Example:</h3>
</div>
<p id="par_id3154046" class="paragraph" dir="auto">The following example listens to events occurring for a BASIC library object.</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Dim oListener As Object
oListener = CreateUnoListener( "ContListener_","com.sun.star.container.XContainerListener" )
</code></pre></div>
<p id="par_id3149294" class="paragraph" dir="auto">The <span class="literal">CreateUnoListener</span> method requires two parameters. The first is <span class="emph">Prefix</span> and is explained in detail below. <span class="emph">Typename</span> second parameter is the fully qualified name of the listener interface.</p>
<p id="par_id3149670" class="paragraph" dir="auto">Every listener must be registered to LibreOffice broadcaster feature. This is performed by binding each listener to its associated object. Bind methods always follow the pattern '<span class="literal">add</span>Foo<span class="literal">Listener</span>', where 'Foo' is the object type of the listener interface, without the 'X'. In this example, the <a target="_blank" href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainer.html#a69e03a743cfa3e99935cac90b5f4e291"><span class="literal">addContainerListener</span></a> method is called to register the <span class="literal">XContainerListener</span>:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Dim oLib As Object
oLib = BasicLibraries.Library1 ' Library1 must exist!
oLib.addContainerListener( oListener ) ' Register the listener
</code></pre></div>
<p id="par_id3154138" class="paragraph" dir="auto">The listener is now registered. When an event occurs, the active listener calls the appropriate method defined in <a target="_blank" href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener.html">com.sun.star.container.XContainerListener</a> interface.</p>
<p id="par_id3148922" class="paragraph" dir="auto">Event-driven registered BASIC subroutines require to use a defined <span class="emph">Prefix</span>. The BASIC run-time system searches for subroutines or functions that have the name 'Prefix+ListenerMethod' and calls them when found. Otherwise, a run-time error occurs.</p>
<p id="par_id3150768" class="paragraph" dir="auto">In this example, <a target="_blank" href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html">com.sun.star.container.XContainerListener</a> interface defines the following methods:</p>
<table border="1" class="" cellpadding="0" cellspacing="0">
<tr>
<th rowspan="" colspan="" class="tableheadcell" dir="auto">
<p id="par_id701666342054257" class="tableheadintable" dir="auto">method</p>
</th>
<th rowspan="" colspan="" class="tableheadcell" dir="auto">
<p id="par_id531666342054257" class="tableheadintable" dir="auto">description</p>
</th>
</tr>
<tr>
<td rowspan="" colspan="" dir="auto">
<p id="par_id11666342054257" class="tablecontentintable" dir="auto"><span class="literal">disposing</span></p>
</td>
<td rowspan="" colspan="" dir="auto">
<p id="par_id841666342054257" class="tablecontentintable" dir="auto"><a target="_blank" href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1lang_1_1XEventListener.html">com.sun.star.lang.XEventListener</a> base interface for all Listener Interfaces</p>
</td>
</tr>
<tr>
<td rowspan="" colspan="" dir="auto">
<p id="par_id11666342054258" class="tablecontentintable" dir="auto"><span class="literal">elementInserted</span></p>
</td>
<td rowspan="" colspan="" dir="auto">
<p id="par_id841666342054258" class="tablecontentintable" dir="auto">Method of the <a target="_blank" href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html">com.sun.star.container.XContainerListener</a> interface</p>
</td>
</tr>
<tr>
<td rowspan="" colspan="" dir="auto">
<p id="par_id11666342054259" class="tablecontentintable" dir="auto">elementRemoved</p>
</td>
<td rowspan="" colspan="" dir="auto">
<p id="par_id841666342054259" class="tablecontentintable" dir="auto">Method of the <a target="_blank" href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html">com.sun.star.container.XContainerListener</a> interface</p>
</td>
</tr>
<tr>
<td rowspan="" colspan="" dir="auto">
<p id="par_id11666342054267" class="tablecontentintable" dir="auto">elementReplaced</p>
</td>
<td rowspan="" colspan="" dir="auto">
<p id="par_id841666342054267" class="tablecontentintable" dir="auto">Method of the <a target="_blank" href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1container_1_1XContainerListener-members.html">com.sun.star.container.XContainerListener</a> interface</p>
</td>
</tr>
</table>
<br>
<p id="par_id3147435" class="paragraph" dir="auto">'ContListener_' used in this example implies that the following subroutines must be implemented in BASIC:</p>
<ul itemprop="Unordered" itemscope="true" itemtype="http://schema.org/ItemList" dir="auto">
<li itemprop="itemListElement" itemscope="true" itemtype="http://schema.org/ItemListUnordered" dir="auto">
<p id="par_id3155411" class="listitem" dir="auto">ContListener_<span class="literal">disposing</span></p>
</li>
<li itemprop="itemListElement" itemscope="true" itemtype="http://schema.org/ItemListUnordered" dir="auto">
<p id="par_id3146923" class="listitem" dir="auto">ContListener_<span class="literal">elementInserted</span></p>
</li>
<li itemprop="itemListElement" itemscope="true" itemtype="http://schema.org/ItemListUnordered" dir="auto">
<p id="par_id3147318" class="listitem" dir="auto">ContListener_<span class="literal">elementRemoved</span></p>
</li>
<li itemprop="itemListElement" itemscope="true" itemtype="http://schema.org/ItemListUnordered" dir="auto">
<p id="par_id3152578" class="listitem" dir="auto">ContListener_<span class="literal">elementReplaced</span></p>
</li>
</ul>
<p id="par_id3150592" class="paragraph" dir="auto">Every listener interface defines a set of controlled event names associated to Uno objects. When an event occurs, it is sent to the method as a parameter. BASIC event methods can also call one another, as long as the appropriate parameter is passed in the <span class="literal">Sub</span> declaration. For example:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Sub ContListener_disposing( oEvent As com.sun.star.lang.EventObject )
MsgBox "disposing"
End Sub
Sub ContListener_elementInserted( oEvent As com.sun.star.container.ContainerEvent )
MsgBox oEvent.Source.' "elementInserted"
End Sub
Sub ContListener_elementRemoved( oEvent As com.sun.star.container.ContainerEvent )
MsgBox "elementRemoved"
End Sub
Sub ContListener_elementReplaced( oEvent As com.sun.star.container.ContainerEvent )
MsgBox "elementReplaced"
End Sub
</code></pre></div>
<p id="par_id3156056" class="paragraph" dir="auto">Not need to include the event object parameter when not used:</p>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
' Minimal implementation of Sub disposing
Sub ContListener_disposing
End Sub
</code></pre></div>
<div class="warning">
<div class="noteicon" dir="auto"><img src="media/icon-themes/res/helpimg/warning.svg" alt="warning" style="width:40px;height:40px;"></div>
<div class="notetext"><p id="par_id621666343214282" dir="auto">Listener methods must <span class="emph">always</span> be implemented to avoid BASIC run-time errors.</p></div>
</div>
<br>
<div class="tip">
<div class="noteicon" dir="auto"><img src="media/icon-themes/res/helpimg/tip.svg" alt="tip" style="width:40px;height:40px;"></div>
<div class="notetext"><p id="par_id101666620765251" dir="auto">Use <a target="_top" href="en-US/text/sbasic/shared/03/sf_exception.html"><span class="literal">ScriptForge</span></a> library console when the BASIC IDE is not easily accessible, that is during events processing. Use the <a target="_top" href="en-US/text/sbasic/shared/03/sf_exception.html#DebugPrint"><span class="literal">DebugPrint</span></a> method to add any relevant information to the console. Console entries can be dumped to a text file or visualized in a dialog window. Use <span class="literal">Trace</span> module of <a target="_top" href="en-US/text/sbasic/guide/access2base.html"><span class="literal">Access2Base</span></a> library as an alternative</p></div>
</div>
<br>
<div class="bascode" itemscope="true" itemtype="http://schema.org/SoftwareSourceCode" itemprop="codeSampleType" content="snippet" data-tooltip="Click on text to copy to clipboard"><pre dir="auto"><code class="language-visual-basic line-numbers">
Sub SF_Trace
GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
svc = CreateScriptService("ScriptForge.Exception")
svc.Console modal:=False
svc.DebugPrint("Lorem", "Ipsum", "...")
End Sub ' SF_Trace
Sub A2B_Trace
GlobalScope.BasicLibraries.LoadLibrary("Access2Base")
Access2Base.Trace.DebugPrint("Lorem", "Ipsum", "...")
Access2Base.Trace.TraceConsole()
End Sub ' A2B_Trace
</code></pre></div>
<a name="relatedtopics"></a><div class="relatedtopics">
<p class="related" itemprop="mentions" dir="auto"><a name="related"></a><span class="emph">Related Topics</span>
</p>
<div class="relatedbody" itemprop="mentions">
<div class="embedded"><p class="embedded" dir="auto"><a target="_top" href="en-US/text/sbasic/python/python_listener.html">Creating Event Listeners</a></p></div>
<p id="N0506" class="paragraph" dir="auto"><a target="_top" href="en-US/text/swriter/01/05060700.html">Events mapping to objects</a></p>
<p id="N0509" class="paragraph" dir="auto">See also <a target="_top" href="en-US/text/sbasic/shared/01040000.html">Document events</a>, <a target="_top" href="en-US/text/shared/02/01170202.html">Form events</a>.</p>
<div class="embedded"><p class="embedded" dir="auto"><a target="_top" href="en-US/text/sbasic/python/python_handler.html">Creating a Dialog Handler</a></p></div>
<div class="embedded"><p class="embedded" dir="auto"><a target="_top" href="en-US/text/sbasic/python/python_document_events.html">Listening to Document Events</a></p></div>
</div>
</div>
</div>
<div id="DonationFrame"></div>
<footer><div id="DEBUG" class="debug">
<h3 class="bug">Help content debug info:</h3>
<p dir="auto">This page is: <a href="https://opengrok.libreoffice.org/xref/help/source/text/sbasic/shared/03132000.xhp" target="_blank">/text/sbasic/shared/03132000.xhp</a></p>
<p dir="auto">Title is: CreateUnoListener Function</p>
<p id="bm_module" dir="auto"></p>
<p id="bm_system" dir="auto"></p>
<p id="bm_HID" dir="auto"></p>
</div></footer>
</body>
</html>